---
title: Black Forest Labs
description: Learn how to use Black Forest Labs models with the AI SDK.
---

# Black Forest Labs Provider

[Black Forest Labs](https://bfl.ai/) provides a generative image platform for developers with FLUX-based models. Their platform offers fast, high quality, and in-context image generation and editing with precise and coherent results.

## Setup

The Black Forest Labs provider is available via the `@ai-sdk/black-forest-labs` module. You can install it with

<Tabs items={['pnpm', 'npm', 'yarn', 'bun']}>
  <Tab>
    <Snippet text="pnpm add @ai-sdk/black-forest-labs" dark />
  </Tab>
  <Tab>
    <Snippet text="npm install @ai-sdk/black-forest-labs" dark />
  </Tab>
  <Tab>
    <Snippet text="yarn add @ai-sdk/black-forest-labs" dark />
  </Tab>

  <Tab>
    <Snippet text="bun add @ai-sdk/black-forest-labs" dark />
  </Tab>
</Tabs>

## Provider Instance

You can import the default provider instance `blackForestLabs` from `@ai-sdk/black-forest-labs`:

```ts
import { blackForestLabs } from '@ai-sdk/black-forest-labs';
```

If you need a customized setup, you can import `createBlackForestLabs` and create a provider instance with your settings:

```ts
import { createBlackForestLabs } from '@ai-sdk/black-forest-labs';

const blackForestLabs = createBlackForestLabs({
  apiKey: 'your-api-key', // optional, defaults to BFL_API_KEY environment variable
  baseURL: 'custom-url', // optional
  headers: {
    /* custom headers */
  }, // optional
});
```

You can use the following optional settings to customize the Black Forest Labs provider instance:

- **baseURL** _string_

  Use a different URL prefix for API calls, e.g. to use a regional endpoint.
  The default prefix is `https://api.bfl.ai/v1`.

- **apiKey** _string_

  API key that is being sent using the `x-key` header.
  It defaults to the `BFL_API_KEY` environment variable.

- **headers** _Record&lt;string,string&gt;_

  Custom headers to include in the requests.

- **fetch** _(input: RequestInfo, init?: RequestInit) => Promise&lt;Response&gt;_

  Custom [fetch](https://developer.mozilla.org/en-US/docs/Web/API/fetch) implementation.
  You can use it as a middleware to intercept requests,
  or to provide a custom fetch implementation for e.g. testing.

## Image Models

You can create Black Forest Labs image models using the `.image()` factory method.
For more on image generation with the AI SDK see [generateImage()](/docs/reference/ai-sdk-core/generate-image).

### Basic Usage

```ts
import { writeFileSync } from 'node:fs';
import { blackForestLabs } from '@ai-sdk/black-forest-labs';
import { experimental_generateImage as generateImage } from 'ai';

const { image, providerMetadata } = await generateImage({
  model: blackForestLabs.image('flux-pro-1.1'),
  prompt: 'A serene mountain landscape at sunset',
});

const filename = `image-${Date.now()}.png`;
writeFileSync(filename, image.uint8Array);
console.log(`Image saved to ${filename}`);
```

### Model Capabilities

Black Forest Labs offers many models optimized for different use cases. Here are a few popular examples. For a full list of models, see the [Black Forest Labs Models Page](https://bfl.ai/models).

| Model                | Description                                                                                                                |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `flux-kontext-pro`   | FLUX.1 Kontext [pro] handles both text and reference images as inputs, enabling targeted edits and complex transformations |
| `flux-kontext-max`   | FLUX.1 Kontext [max] with improved prompt adherence and typography generation                                              |
| `flux-pro-1.1-ultra` | Ultra-fast, ultra high-resolution image creation                                                                           |
| `flux-pro-1.1`       | Fast, high-quality image generation from text.                                                                             |

Black Forest Labs models support aspect ratios from 3:7 (portrait) to 7:3 (landscape).

#### Modify Image

Transform existing images using text prompts.

```ts
import {
  blackForestLabs,
  BlackForestLabsImageProviderOptions,
} from '@ai-sdk/black-forest-labs';
import { experimental_generateImage as generateImage } from 'ai';

// Example: Modify existing image
await generateImage({
  model: blackForestLabs.image('flux-kontext-pro'),
  prompt: 'Put a donut next to the flour.',
  providerOptions: {
    blackForestLabs: {
      inputImage: '<base64 converted image>',
    } satisfies BlackForestLabsImageProviderOptions,
  },
});
```

### Provider Options

Black Forest Labs image models support flexible provider options through the `providerOptions.blackForestLabs` object. You can pass any parameters supported by the specific endpoint's API. The supported parameters depend on the used model ID:

- **imagePrompt** - Base64-encoded image to use as additional visual context for generation
- **imagePromptStrength** - Strength of the image prompt influence on generation (0.0 to 1.0)
- **inputImage** - Base64 encoded image or URL of image to use as reference. Supports up to 20MB or 20 megapixels.
- **outputFormat** - Desired format of the output image. Can be “jpeg” or “png”.
- **promptUpsampling** - If true, performs upsampling on the prompt
- **raw** - Enable raw mode for more natural, authentic aesthetics
- **safetyTolerance** - Moderation level for inputs and outputs. Value ranges from 0 (most strict) to 6 (more permissive).
- **webhookSecret** - Secret for webhook signature verification, sent in the `X-Webhook-Secret` header.
- **webhookUrl** - URL for asynchronous completion notification. Must be a valid HTTP/HTTPS URL.
- **pollIntervalMillis** - Interval in milliseconds between polling attempts (default 500ms)
- **pollTimeoutMillis** - Overall timeout in milliseconds for polling before timing out (default 60s)
- **width** - Output width in pixels for models that support explicit dimensions. Range 256–1920, default 1024. When set, this overrides any width derived from `size`.
- **height** - Output height in pixels for models that support explicit dimensions. Range 256–1920, default 768. When set, this overrides any height derived from `size`.
- **steps** - Number of inference steps. Higher values may improve quality but increase generation time
- **guidance** - Guidance scale for generation. Higher values follow the prompt more closely
- **inputImage2 … inputImage10** - Additional reference images (base64 string or URL) for models that support multiple inputs, used alongside `inputImage`.

### Regional Endpoints

By default, requests are sent to `https://api.bfl.ai/v1`. You can select a [regional endpoint](https://docs.bfl.ai/api_integration/integration_guidelines#regional-endpoints) by setting `baseURL` when creating the provider instance:

```ts
import { createBlackForestLabs } from '@ai-sdk/black-forest-labs';

const blackForestLabs = createBlackForestLabs({
  baseURL: 'https://api.eu.bfl.ai/v1', // or https://api.us.bfl.ai/v1
});
```
